home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Framework / Includes / UDocument.h < prev    next >
Encoding:
Text File  |  1996-04-03  |  20.5 KB  |  582 lines  |  [TEXT/MPS ]
  1. // UDocument.h
  2. // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved.
  3.  
  4. #ifndef __UDOCUMENT__
  5. #define __UDOCUMENT__
  6.  
  7. // MacApp
  8.  
  9. #ifndef __UCOMMANDHANDLER__
  10. #include "UCommandHandler.h"
  11. #endif
  12.  
  13. #ifndef __ULISTITERATOR__
  14. #include "UListIterator.h"
  15. #endif
  16.  
  17. #ifndef __USCRIPTABLEOBJECT__
  18. #include "UScriptableObject.h"
  19. #endif
  20.  
  21. // CALib
  22.  
  23. #if qContainer
  24.     #ifndef _CADEFS_
  25.     #include "CADefs.h"
  26.     #endif
  27. #endif
  28.  
  29.  
  30. //----------------------------------------------------------------------------------------
  31. // Forward and external class declarations. 
  32. //----------------------------------------------------------------------------------------
  33.  
  34. class TCloseDocCommand;
  35. class TDesignator;
  36. class TDocument;
  37. class TFile;
  38. class TList;
  39. class TPrintHandler;
  40. class TPrintInfo;
  41. class TSaveDocCommand;
  42. class TStream;
  43. class TView;
  44. class TWindow;
  45.  
  46. //----------------------------------------------------------------------------------------
  47. // CWindowIterator
  48. //----------------------------------------------------------------------------------------
  49.  
  50. class CWindowIterator : public CObjectIterator
  51. {
  52. public:
  53.     CWindowIterator(const TDocument* itsDocument,
  54.                     ArrayIndex itsLowBound, ArrayIndex itsHighBound,
  55.                     Boolean itsForward);
  56.  
  57.     CWindowIterator(const TDocument* itsDocument, Boolean itsForward);
  58.  
  59.     CWindowIterator(const TDocument* itsDocument);
  60.     
  61.     virtual ~CWindowIterator();
  62.     
  63.     inline TWindow* CurrentWindow()
  64.     { return (TWindow *)this->CurrentObject(); }
  65.         // returns the current window
  66.     
  67.     inline TWindow* FirstWindow()
  68.     { return (TWindow*)this->FirstObject(); }
  69.         // return the first window in the iteration
  70.  
  71.     inline TWindow* NextWindow()
  72.     { return (TWindow*)this->NextObject(); }
  73.         // advances the iteration and then returns the window
  74. };
  75.  
  76.  
  77. //----------------------------------------------------------------------------------------
  78. // TDocument: Corresponds to a Finder document. Manages document data in files and in main
  79. // memory.
  80. //----------------------------------------------------------------------------------------
  81.  
  82. class TDocument : public TCommandHandler, public MScriptableObject
  83. {
  84.     MA_DECLARE_CLASS;
  85.     
  86. public:
  87.  
  88.     TDocument();
  89.         // Constructor
  90.         
  91.     void IDocument();
  92.         // Initialization method for TDocument.
  93.  
  94.     virtual ~TDocument();
  95.         // This does not call FreeData by default, since you may need to control the order
  96.         // in which things are freed. Your override of TDocument::Free can call FreeData if
  97.         // convenient.
  98.  
  99.     virtual void FreeData();
  100.         // Called when a document is reverted, in order to free it's data objects. You may
  101.         // also wish to call this from you document's Free method, if convenient.
  102.  
  103.     virtual void FreeFromClipboard();
  104.         // Called to free a Clipboard document. Simply calls Free.
  105.         
  106.     virtual Boolean GetIsGhostDocument() const;
  107.     
  108.     virtual void SetIsGhostDocument(const Boolean newIsGhostDocument);
  109.  
  110.     virtual void RegainControl();
  111.         // Called just after the application has been resumed to allow the
  112.         // document to make any necessary adjustments to outside activities.
  113.  
  114.     //------------------------------------------------------------------------------------
  115.     // Opening / Printing Documents
  116.     //------------------------------------------------------------------------------------
  117.  
  118.     virtual Boolean FindDocument(TFile* aFile);
  119.         // True if this document is already open
  120.  
  121.     virtual void DoInitialState();
  122.         // Called for 'New', 'Revert' to blank, Open Tool. Default is to do nothing; You
  123.         // may need to do further initialization that you would not do in case of an Open
  124.  
  125.     virtual void DoMakeViews(Boolean forPrinting);
  126.         // Create all necessary views for this document (based on forPrinting flag) and
  127.         // store into fields of your document. The document will then be sent Print.
  128.  
  129.     virtual void DoPostMakeViews(Boolean forPrinting);
  130.         // Called after DoMakeViews. Calls ShowWindows.
  131.  
  132.     virtual void AttachPrintHandler(TPrintHandler* itsPrintHandler);
  133.         // Creates a TPrintMenuBehavior and adds it to this document
  134.  
  135.     virtual void DetachPrintHandler(TPrintHandler* itsPrintHandler);
  136.         // Deletes a TPrintMenuBehavior that's been added to this document
  137.  
  138.     virtual void OpenAgain(CommandNumber itsCommandNumber, TDocument* openingDoc);
  139.         // Called if the user tries to open the same document twice. openingDoc will be
  140.         // the document object being opened (note that this is not true for TApplication::OpenOld,
  141.         // for which openingDoc is null). Default brings this to the front and calls
  142.         // Failure(noErr, 0), which will abort opening the document. (The goal is to
  143.         // prevent the user from having 2 copies of the same document open, in which case
  144.         // they could make incompatible changes to both.) You might override this if you
  145.         // want to open a second window on the same document. In the ideal case, you
  146.         // should make both windows display exactly the same data, and changes made to one
  147.         // should be reflected in the other. You could also override this to create a
  148.         // read-only copy of the document.
  149.  
  150.     virtual short PoseSaveDialog();
  151.         // If the document has been changed (fChangeCount > 0), then the user is asked to
  152.         // save the document. PoseSaveDialog returns cancel, kYesButton or kNoButton,
  153.         // depending on the button chosen by the user. If the document has not been
  154.         // changed then kNoButton is returned.
  155.  
  156.     virtual void ReadDocument(Boolean forPrinting);
  157.         // Called to read an existing file for display or printing.
  158.  
  159.     virtual void ReadStationery(TFile* itsNewFile);
  160.         // Called to read an existing stationery pad and display its contents in a new
  161.         // untitled document.
  162.  
  163.     virtual void ShowWindows();
  164.         // Called when opening the document initially; default is to call OpenWindow for
  165.         // all windows that have fFlags.openInitially true
  166.  
  167.     virtual void UntitledName(CStr255& noName);
  168.         // Called to supply a name for an untitled document. If this returns '' then the
  169.         // windows are not renamed from the value specified in their titles.
  170.  
  171.  
  172.     //------------------------------------------------------------------------------------
  173.     // Saving Documents
  174.     //------------------------------------------------------------------------------------
  175.  
  176.     virtual long GetChangeCount();
  177.         // Gets the document change count
  178.  
  179.     // Added for 3.5
  180.     virtual Boolean IsChanged();
  181.         // If the document has been changed
  182.  
  183.     virtual void SetChangeCount(long newChangeCount);
  184.         // Sets the document change count
  185.  
  186.     virtual void GetSaveLocation(CommandNumber itsCommandNumber, CAEDesc& theSaveDesc);
  187.         // Creates an CAEDesc describing where the document would be saved
  188.  
  189.     virtual void DoSave(CommandNumber itsCommandNumber);
  190.         // Handle the cSave, cSaveAs, and cSaveCopy commands
  191.  
  192.     virtual void SaveDocument(CommandNumber itsCommandNumber);
  193.         // Try to save the document to disk
  194.  
  195.     virtual void SaveAgain(CommandNumber itsCommandNumber, TDocument* savingDoc);
  196.         // Called when the user tries to Save As or Save a Copy In and specifies the name
  197.         // of a document that is already opened. The default case calls
  198.         // Failure(errSaveAgain, messageSaveFailed) to display an error. (The goal is to
  199.         // prevent the user from having 2 copies of the same document open, in which case
  200.         // they might make incompatible changes to both copies.) savingDoc is the document
  201.         // being saved
  202.  
  203.  
  204.     //------------------------------------------------------------------------------------
  205.     // Closing Documents
  206.     //------------------------------------------------------------------------------------
  207.  
  208.     virtual void Close();
  209.         // Close a document.  Notifies others of closing and then closes up all
  210.         // associated windows.  ??? NOTE: Must never be called for a document
  211.         // related to a view in the Clipboard.
  212.  
  213.     virtual void CloseAndFree();
  214.         // Close a document and free it.
  215.         
  216.     virtual TCloseDocCommand* MakeCloseCommand();
  217.         // This method creates a document saving command appropriate to this type
  218.         // of document.
  219.  
  220.     virtual void DoClose(CommandNumber aCommand,
  221.                          Boolean useAppleEvent = TRUE);
  222.         // This method creates a document closing command appropriate to this type
  223.         // of document and then posts it.  Pass a FALSE if this close is NOT
  224.         // supposed to generate an AppleEvent.
  225.  
  226.     //------------------------------------------------------------------------------------
  227.     // Revert
  228.     //------------------------------------------------------------------------------------
  229.  
  230.     virtual void RevertDocument();
  231.         // IF fSaveExists is true then reverts to the file saved on disk, otherwise merely
  232.         // resets the print handler and calls doInitialState. Calls FreeData to free any
  233.         // existing data and commits any currently active command.
  234.  
  235.     virtual void Abandon();
  236.         // Called when a document is closed and changes are being abandoned. For memory
  237.         // based documents the default behaviour of doing nothing is OK. For disk based
  238.         // documents that change the original copy this is the place to override to put
  239.         // back the original contents if you still have it available somewhere (a scratch
  240.         // file?)
  241.  
  242.     virtual void ShowReverted();
  243.         // Called after Revert to show brand new document; default tells each view to
  244.         // ShowReverted
  245.  
  246.  
  247.     //------------------------------------------------------------------------------------
  248.     // Miscellaneous
  249.     //------------------------------------------------------------------------------------
  250.  
  251.     virtual void DoWriteData(const OSType aScrapType,
  252.                                               TDesignator* aDesignator,
  253.                                               TStream* aStream);
  254.         // Given a designator and a stream, writes the designated data to the stream.
  255.  
  256.     virtual void DoReadData(const OSType aScrapType,
  257.                                               TDesignator* aDesignator,
  258.                                               TStream* aStream, long length);
  259.         // Given a designator and a stream, read the designated data from the stream.
  260.  
  261.  
  262.     //------------------------------------------------------------------------------------
  263.     // designator management methods
  264.     //------------------------------------------------------------------------------------
  265.  
  266.     virtual TDesignator* GetUserSelection();
  267.         // Returns the designator for the user selection (if any).
  268.  
  269.     virtual void SetUserSelection(TDesignator* newSelection);
  270.         // Sets the designator for the user selection (if any).
  271.  
  272.     virtual void UserSelectionChanged(TView* changedView);
  273.         // Call this whenever the user's selection changes. Subclasses should implement
  274.         // the appropriate behavior for their corresponding user selection TDesignator.
  275.  
  276.     virtual void RevealSelection(TDesignator* aSelection);
  277.         // OVERRIDE this; bring this designation into user's view
  278.     
  279.     virtual void RevealUndoRedo(TCommand* command); // override
  280.         // Make this context visible after undo/redo. 
  281.  
  282.     virtual void GetTitle(CStr255& aTitle);
  283.         // Returns the name of the fFile or '' if the file does not exist
  284.  
  285.     virtual void SetTitle(const CStr255& aTitle);
  286.         // Does fFile->SetName to aTitle and calls SetTitleForDoc for each window of the
  287.         // document.
  288.  
  289.     virtual void Changed(ChangeID theChange, 
  290.                                 TObject* changedBy);
  291.         // Updates fChangeCount. Calls Inherited::Changed to notify dependents.
  292.  
  293.  
  294.     //------------------------------------------------------------------------------------
  295.     // Command Handlers
  296.     //------------------------------------------------------------------------------------
  297.  
  298.     virtual void DoMenuCommand(CommandNumber aCommandNumber);
  299.         // Handles the default menu commands associated with a document and must be
  300.         // overridden to handle any additional items.
  301.  
  302.     virtual void DoSetupMenus();
  303.         // Setup the documents menus, this handles the default menus and must be
  304.         // overridden for any additional items.
  305.  
  306.  
  307.     //------------------------------------------------------------------------------------
  308.     // Hierarchy
  309.     //------------------------------------------------------------------------------------
  310.  
  311.     virtual void AddView(TView* aView);
  312.         // Adds the view to the end of the document's view list.
  313.  
  314.     virtual void AddWindow(TWindow* aWindow);
  315.         // Adds the window to the end of the document's window list.
  316.  
  317.     virtual void CloseWindow(TWindow* aWindow);
  318.         // Called to close a window associated with a document. Document gets to
  319.         // decide whether to really close the window or not and whether to close itself or
  320.         // if there are no more windows. Does nothing if the window is not associated with the doc.
  321.  
  322.     virtual void DeleteView(TView* viewToDelete);
  323.         // Deletes the view from the document's view list.
  324.  
  325.     virtual void DeleteWindow(TWindow* windowToDelete);
  326.         // Deletes the window from the document's window list.
  327.  
  328.     //------------------------------------------------------------------------------------
  329.     // Scripting Support
  330.     //------------------------------------------------------------------------------------
  331.  
  332.     virtual DescType GetSpecifierForm(); // override
  333.  
  334.     virtual void DoScriptCommand(CommandNumber    aCommandNumber,
  335.                                 TAppleEvent*     message,
  336.                                 TAppleEvent*     reply);
  337.         // Dispatches the send document event
  338.  
  339.     virtual MScriptableObject* GetContainedObject(DescType desiredType,
  340.                                               DescType selectionForm,
  341.                                               const CAEDesc& selectionData);
  342.  
  343.     virtual Boolean GetObjectProperty(CAEDesc& thePropertyValue,
  344.                                     DescType whichProperty,
  345.                                     const CAEDesc& desiredType);
  346.  
  347.     virtual void GetSetPropertyInfo(DescType whichProperty,
  348.                                 CommandNumber& cmdNum,
  349.                                 Boolean& canUndo,
  350.                                 Boolean& causesChange,
  351.                                 TCommandHandler* &theContext);
  352.                                 
  353.     virtual void SetObjectProperty(const CAEDesc& thePropertyValue,
  354.                                     DescType whichProperty);
  355.  
  356.     virtual void DoAESetData(TAppleEvent* message,
  357.                            TAppleEvent* reply);
  358.  
  359.     virtual void DoAEClose(TAppleEvent* message,
  360.                            TAppleEvent* reply);
  361.                            
  362.     virtual void DoAERevert(TAppleEvent* message, TAppleEvent* reply);
  363.  
  364.     virtual void DoAESave(TAppleEvent* message,
  365.                           TAppleEvent* reply);
  366.  
  367.     //------------------------------------------------------------------------------------
  368.     // Container Application Support
  369.     //------------------------------------------------------------------------------------
  370.  
  371. #if qContainer
  372.     virtual CADocumentRef GetContainer();
  373.         // Override to return the container document reference. 
  374.         // For CALib we have to break the encapsulation of TWindow and TDocument
  375.         // so we can find its CADocumentRef. 
  376.         // $$$$$ This method will go away as soon as we can find a better way to
  377.         //         convert a WindowPtr to a CADocumentRef. 
  378. #endif
  379.  
  380. protected:
  381.     short OpenWindowCount();
  382.  
  383.  
  384. //----------------------------------------------------------------------------------------
  385. // data members
  386. //----------------------------------------------------------------------------------------
  387.  
  388. public:
  389.     CStr255 fTitle;                                // Title of the document
  390.  
  391.     TList* fWindowList;                            // list of windows belonging to this
  392.                                                 // document
  393.  
  394.     TList* fViewList;                            // list of views belonging to document
  395.  
  396.     TDesignator* fUserSelection;                // When there is a single user-selection
  397.                                                 // for a document this is it.
  398.  
  399.     TPrintInfo* fPrintInfo;                        // if non-NULL, this is an object that has
  400.                                                 // the print setup and job info records
  401.  
  402.     long fChangeCount;                            // master count of changes since last Save
  403.  
  404.     Boolean fSavePrintInfo;                        // if true for a document saved on disk,
  405.                                                 // the 'print info' record of the
  406.                                                 // fDocPrintHandler will be written out to
  407.                                                 // the data fork before other writing
  408.                                                 // takes place
  409.  
  410.     Boolean fSaveUserSelection;                    // if true, the user selection will be saved
  411.  
  412. #if qAttachable
  413.     Boolean fSaveAttachedScript;                // if true, the attached script will be saved
  414. #endif
  415.  
  416.     Boolean fSharePrintInfo;                    // if true, then all printHandlers
  417.                                                 // associated with views belonging to the
  418.                                                 // same document will share the same
  419.                                                 // 'print info' record
  420.  
  421.     Boolean fReopenAlert;                        // whether to give an alert if user
  422.                                                 // reopens doc
  423.  
  424.     Boolean fAskOnClose;                        // Ask to save before closing
  425.  
  426.     Boolean fCommitOnSave;                        // Commit the last command before saving
  427.                                                 // the document, if it affected the
  428.                                                 // document. This defaults to true, but
  429.                                                 // carefully written applications could
  430.                                                 // set this false.
  431. protected:
  432.     
  433.     Boolean fIsGhostDocument;                    // If true, the document iterator of type
  434.                                                 // CNoGhostDocs will skip this document.
  435.                                                 // Will be true if this document is a clipboard
  436.                                                 // document, or if it is a non-scriptable document
  437.  
  438. //----------------------------------------------------------------------------------------
  439. // static data members
  440. //----------------------------------------------------------------------------------------
  441.  
  442.     static short gNumUntitled;
  443.         // The number to assign to the next Untitled document (assuming that the app provides
  444.         // a template for filling in the number. You must change STR# resource with ID 0/ index
  445.         // 3 to read (for example) Untitled-<<<#>>>.
  446.  
  447. };
  448.  
  449. //----------------------------------------------------------------------------------------
  450. // TSaveDocCommand: Tells the document to save itself.
  451. //----------------------------------------------------------------------------------------
  452.  
  453. class TSaveDocCommand : public TCommand
  454. {
  455.     MA_DECLARE_CLASS;
  456.     
  457. public:
  458.     TSaveDocCommand();
  459.     virtual ~TSaveDocCommand();
  460.                 
  461.     void ISaveDocCommand(CommandNumber itsCommandNumber,
  462.                                          TDocument* itsDocument);
  463.     void ISaveDocCommand(TDocument* itsDocument,
  464.                          TAppleEvent* message,
  465.                          TAppleEvent* reply);
  466.         // Initialize the TSaveDocCommand procedurally. 
  467.  
  468.     virtual void DoIt();
  469.         // Actually perform the document saving. 
  470.         
  471.     virtual TAppleEvent* MakeAppleEvent();
  472.  
  473. //----------------------------------------------------------------------------------------
  474. // data members
  475. //----------------------------------------------------------------------------------------
  476. public:
  477.     TDocument* fDocument;    // The document to close
  478.     
  479. protected:
  480.     TAppleEvent* fMessage;
  481.     TAppleEvent* fReply;
  482.  
  483.     enum
  484.     {
  485.         kDoSave,
  486.         kDontSave,
  487.         kAskSave
  488.     };
  489.     
  490.     short            fSavingState;
  491. };
  492.  
  493. //----------------------------------------------------------------------------------------
  494. // TRevertDocCommand: Tells the document to revert after checking with the user.
  495. //----------------------------------------------------------------------------------------
  496.  
  497. class TRevertDocCommand : public TCommand
  498. {
  499.     MA_DECLARE_CLASS;
  500.     
  501. public:
  502.  
  503.     TRevertDocCommand();
  504.         // Constructor
  505.     virtual ~TRevertDocCommand();
  506.         // Destructor
  507.         
  508.     Boolean IRevertDocCommand(CommandNumber itsCommandNumber,
  509.                               TDocument* itsDocument);
  510.     void IRevertDocCommand(TDocument* itsDocument,
  511.                                           TAppleEvent* message,
  512.                                           TAppleEvent* reply,
  513.                                           Boolean* statusP);
  514.         // Initialize the RevertDocCommand procedurally.
  515.  
  516.     virtual void DoIt();
  517.         // tell the document to revert if the user says OK.
  518.  
  519.     virtual TAppleEvent* MakeAppleEvent();
  520.  
  521. //----------------------------------------------------------------------------------------
  522. // data members
  523. //----------------------------------------------------------------------------------------
  524. public:
  525.     TDocument* fChangedDocument;                // the document changed by this command
  526.     
  527. protected:
  528.     Boolean*        fInProcessP;
  529. };
  530.  
  531. //----------------------------------------------------------------------------------------
  532. // TCloseDocCommand: Closes a document.
  533. //----------------------------------------------------------------------------------------
  534.  
  535. class TCloseDocCommand : public TCommand
  536. {
  537.     MA_DECLARE_CLASS;
  538.     
  539. public:
  540.     
  541.     TCloseDocCommand();
  542.     virtual ~TCloseDocCommand();
  543.         
  544.     void ICloseDocCommand(CommandNumber itsCommandNumber,
  545.                           TDocument* itsDocument);
  546.     void ICloseDocCommand(TDocument* itsDocument,
  547.                           TAppleEvent* message,
  548.                           TAppleEvent* reply);
  549.         // Initialize the CloseDocCommand procedurally. 
  550.     
  551.     virtual TAppleEvent* MakeAppleEvent();
  552.         // Make an Apple Event equivalent to the command.
  553.  
  554.     virtual void DoIt();
  555.         // Actually perform the document closing. 
  556.         
  557. //----------------------------------------------------------------------------------------
  558. // data members
  559. //----------------------------------------------------------------------------------------
  560. public:
  561.     TDocument* fDocument;    // The document to close
  562.     
  563. protected:
  564.     TAppleEvent* fMessage;
  565.     TAppleEvent* fReply;
  566.  
  567.     enum ESavingState
  568.     {
  569.         kUnknown,
  570.         kAskSave,
  571.         kDoSave,
  572.         kDontSave,
  573.         kCancelled
  574.     };
  575.     
  576.     ESavingState    fSavingState;
  577.  
  578.  
  579. };
  580.  
  581. #endif // __UDOCUMENT__
  582.